/**
 * A framework for lock functionality in a Lumis Portal environment.
 * <p>
 * The locking scope of this method is the whole Lumis Portal cluster.
 * For example, the lock for the same resourceId may be obtained in different 
 * servers and used as a mutex to synchronize executions in them.
 * If it is desired that the locking does not occur in the Lumis Portal cluster 
 * scope, but only in a single JVM, consider using standard Java locking mechanisms.
 * <p>
 * The distributed lock performance is much lower than of a non-distributed lock 
 * (as {@link java.util.concurrent.locks.ReentrantLock} for example), and as such, 
 * it may be not suitable for intense locking operations. The distributed 
 * implementation is based on the database, and as such, has the minimal cost of a
 * database statement execution for each acquisition or release of a lock. 
 * <p>
 * The locks are not associated to the thread that obtained them. Any thread
 * may manipulate the lock objects. If a lock object was used to acquire
 * a lock, this same object must be used to release it.
 * <p>
 * The entry point for this framework is {@link lumis.portal.lock.ILockManager},
 * and it may be obtained by 
 * {@link lumis.portal.manager.ManagerFactory#getLockManager()}.
 * <p>
 * Example usage:
 * <code>
 * Lock lock = ManagerFactory.getLockManager().getLock("com.example.my.resource.id");
 * lock.lock();
 * try
 * {
 *   // this block will be executed only by a single thread simultaneously in 
 *   // the whole Lumis Portal Cluster.
 * }
 * finally
 * {
 *   lock.unlock();
 * }
 * </code>
 * <p>
 * Note that the locks have a timeout as configured in lumisportalconfig.xml.
 * This is to prevent the locks from being permanently acquired on a server 
 * crash event. But as a consequence, the user of this framework should 
 * guarantee that the lock is not held longer than the timeout configured,
 * otherwise the lock semantics will not be obeyed (it may be automatically
 * unlocked after the timeout).
 * 
 * @see lumis.portal.lock.ILockManager
 * @see java.util.concurrent.locks.Lock
 * 
 * @since 4.2.0
 * @version $Revision: 9601 $ $Date: 2008-07-18 15:38:17 -0300 (Fri, 18 Jul 2008) $
 */
package lumis.portal.lock;